JSON (JavaScript Object Notation) is one of the most common formats used by REST APIs to exchange data between a Flutter application and a backend server. In Flutter, JSON responses are usually received as strings and then decoded into Dart objects such as Map, List, and custom model classes.
Flutter provides the dart:convert library for decoding and encoding JSON, while the http package is commonly used to communicate with APIs.
A JSON response is structured data returned by a server after an API request. For example, an API may return the following user information:
{
"id": 101,
"name": "Rahul Sharma",
"email": "[email protected]",
"age": 25,
"isActive": true
}Flutter receives this response as text and needs to decode it before the application can work with individual fields.
| JSON Type | Example | Dart Representation |
|---|---|---|
| String | "Rahul" | String |
| Number | 25 | int / double |
| Boolean | true | bool |
| Object | {"id": 1} | Map |
| Array | [1, 2, 3] | List |
| Null | null | null |
A typical API-to-UI flow looks like this:
Flutter App
↓
HTTP Request
↓
Backend API
↓
JSON Response
↓
response.body
↓
jsonDecode()
↓
Map / List
↓
Dart Model Object
↓
Flutter UI
For example:
API Response
↓
"{\"id\":1,\"name\":\"Rahul\"}"
↓
jsonDecode()
↓
Map
↓
User.fromJson()
↓
User object
↓
Text(user.name)
For API-based JSON processing, the http package is commonly used.
flutter pub add httpThe JSON conversion functions are available in Dart's built-in dart:convert library.
import 'dart:convert';
import 'package:http/http.dart' as http;
When an HTTP request is completed, the response contains information such as the status code, headers, and response body.
final response = await http.get(
Uri.parse('https://example.com/api/users'),
);
print(response.statusCode);
print(response.body);
The response.body value is generally a String containing the server response.
The jsonDecode() function converts a JSON string into Dart data.
import 'dart:convert';
const jsonString = '''
{
"id": 1,
"name": "Rahul",
"email": "[email protected]"
}
''';
final data = jsonDecode(jsonString);
print(data['id']);
print(data['name']);
print(data['email']);
The result of decoding a JSON object is commonly handled as a Map.
A JSON object can be explicitly converted into a Dart map.
final Map userData =
jsonDecode(jsonString) as Map;
print(userData['name']);
This allows individual JSON properties to be accessed using their keys.
final data = jsonDecode(jsonString) as Map;
final int id = data['id'] as int;
final String name = data['name'] as String;
final String email = data['email'] as String;
print(id);
print(name);
print(email);
Type casting helps Dart understand what type of value is expected and provides better type safety.
APIs often return a list of objects instead of a single object.
[
{
"id": 1,
"name": "Rahul"
},
{
"id": 2,
"name": "Priya"
},
{
"id": 3,
"name": "Amit"
}
]
This response can be decoded into a Dart list:
final List users = jsonDecode(jsonString);
for (final user in users) {
print(user['name']);
}
final List> users =
(jsonDecode(jsonString) as List)
.cast>();
for (final user in users) {
print(user['name']);
}
A common process is to send an HTTP request, check the status code, decode the response body, and process the resulting data.
Future fetchUser() async {
final response = await http.get(
Uri.parse('https://jsonplaceholder.typicode.com/users/1'),
);
if (response.statusCode == 200) {
final data = jsonDecode(response.body) as Map;
print(data['name']);
print(data['email']);
} else {
throw Exception('Failed to load user');
}
}
JSON should generally be processed only after determining whether the HTTP request was successful.
if (response.statusCode == 200) {
final data = jsonDecode(response.body);
print(data);
} else {
throw Exception(
'Request failed with status ${response.statusCode}',
);
}
| Status Code | Meaning |
|---|---|
| 200 | OK |
| 201 | Created |
| 204 | No Content |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 500 | Internal Server Error |
| 503 | Service Unavailable |
Instead of working with dynamic maps throughout the application, JSON data can be converted into strongly typed Dart objects.
class User {
final int id;
final String name;
final String email;
const User({
required this.id,
required this.name,
required this.email,
});
factory User.fromJson(Map json) {
return User(
id: json['id'] as int,
name: json['name'] as String,
email: json['email'] as String,
);
}
}
The model can then be created from the decoded JSON:
final data = jsonDecode(response.body) as Map;
final user = User.fromJson(data);
print(user.name);
print(user.email);
The fromJson() method is commonly used to convert JSON data into a Dart model object.
factory User.fromJson(Map json) {
return User(
id: json['id'] as int,
name: json['name'] as String,
email: json['email'] as String,
);
}
The basic conversion is:
JSON Map
↓
User.fromJson()
↓
User Object
When Dart objects need to be sent back to an API, they can be converted into JSON-compatible maps.
class User {
final int id;
final String name;
final String email;
const User({
required this.id,
required this.name,
required this.email,
});
factory User.fromJson(Map json) {
return User(
id: json['id'] as int,
name: json['name'] as String,
email: json['email'] as String,
);
}
Map toJson() {
return {
'id': id,
'name': name,
'email': email,
};
}
}
The object can then be encoded:
final user = User(
id: 1,
name: 'Rahul',
email: '[email protected]',
);
final jsonString = jsonEncode(user.toJson());
print(jsonString);
When an API returns multiple users, each JSON object can be converted into a User object.
List parseUsers(String responseBody) {
final List data = jsonDecode(responseBody);
return data
.map(
(item) => User.fromJson(
item as Map,
),
)
.toList();
}
The result is a strongly typed list:
final List users = parseUsers(response.body);
for (final user in users) {
print(user.name);
}
Real-world APIs often contain nested objects.
{
"id": 1,
"name": "Rahul",
"address": {
"city": "Mumbai",
"country": "India"
}
}
class Address {
final String city;
final String country;
const Address({
required this.city,
required this.country,
});
factory Address.fromJson(Map json) {
return Address(
city: json['city'] as String,
country: json['country'] as String,
);
}
}
class User {
final int id;
final String name;
final Address address;
const User({
required this.id,
required this.name,
required this.address,
});
factory User.fromJson(Map json) {
return User(
id: json['id'] as int,
name: json['name'] as String,
address: Address.fromJson(
json['address'] as Map,
),
);
}
}
Some API fields may contain null. Dart's null safety should be considered when processing such responses.
{
"id": 1,
"name": "Rahul",
"phone": null
}
The model can use a nullable type:
class User {
final int id;
final String name;
final String? phone;
const User({
required this.id,
required this.name,
this.phone,
});
factory User.fromJson(Map json) {
return User(
id: json['id'] as int,
name: json['name'] as String,
phone: json['phone'] as String?,
);
}
}
If an API field may be missing or null, a default value can sometimes be used.
final String name = json['name'] as String? ?? 'Unknown User';
Example:
class User {
final String name;
const User({required this.name});
factory User.fromJson(Map json) {
return User(
name: json['name'] as String? ?? 'Unknown User',
);
}
}
{
"id": 1,
"isActive": true
}
final bool isActive = json['isActive'] as bool;
if (isActive) {
print('User is active');
}
APIs may return integer or decimal values.
{
"id": 10,
"price": 499.99,
"quantity": 3
}
final int quantity = json['quantity'] as int;
final double price = (json['price'] as num).toDouble();
print(quantity);
print(price);
Using num before converting to double can be useful when an API may represent a numeric value as either an integer or decimal.
JSON does not have a dedicated DateTime type. Dates are commonly returned as strings.
{
"createdAt": "2026-09-19T10:30:00Z"
}
Convert the string into a Dart DateTime:
final DateTime createdAt =
DateTime.parse(json['createdAt'] as String);
print(createdAt);
Inside a model:
class Product {
final int id;
final DateTime createdAt;
const Product({
required this.id,
required this.createdAt,
});
factory Product.fromJson(Map json) {
return Product(
id: json['id'] as int,
createdAt: DateTime.parse(
json['createdAt'] as String,
),
);
}
}
JSON may be invalid, incomplete, or different from the structure expected by the application. Parsing should therefore be handled carefully.
try {
final data = jsonDecode(response.body);
print(data);
} on FormatException catch (error) {
print('Invalid JSON: $error');
} catch (error) {
print('Unexpected error: $error');
}
One common mistake is assuming that every API returns an object.
{
"id": 1,
"name": "Rahul"
}
Processing:
final data =
jsonDecode(response.body) as Map;
[
{
"id": 1,
"name": "Rahul"
},
{
"id": 2,
"name": "Priya"
}
]
Processing:
final data = jsonDecode(response.body) as List;
FutureBuilder can be used to manage asynchronous API responses and display loading, success, and error states.
Future fetchUser() async {
final response = await http.get(
Uri.parse('https://jsonplaceholder.typicode.com/users/1'),
);
if (response.statusCode == 200) {
final data =
jsonDecode(response.body) as Map;
return User.fromJson(data);
}
throw Exception('Failed to load user');
}
Use the Future in the widget:
late Future futureUser;
@override
void initState() {
super.initState();
futureUser = fetchUser();
}
Display the result:
FutureBuilder(
future: futureUser,
builder: (context, snapshot) {
if (snapshot.connectionState == ConnectionState.waiting) {
return const CircularProgressIndicator();
}
if (snapshot.hasError) {
return Text('Error: ${snapshot.error}');
}
if (snapshot.hasData) {
final user = snapshot.data!;
return Column(
children: [
Text(user.name),
Text(user.email),
],
);
}
return const Text('No data found');
},
)
The following example demonstrates API request, JSON decoding, model conversion, and displaying the result.
import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
class User {
final int id;
final String name;
final String email;
const User({
required this.id,
required this.name,
required this.email,
});
factory User.fromJson(Map json) {
return User(
id: json['id'] as int,
name: json['name'] as String,
email: json['email'] as String,
);
}
}
Future fetchUser() async {
final response = await http.get(
Uri.parse('https://jsonplaceholder.typicode.com/users/1'),
);
if (response.statusCode == 200) {
final json =
jsonDecode(response.body) as Map;
return User.fromJson(json);
}
throw Exception('Failed to load user');
}
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
appBar: AppBar(
title: const Text('JSON Response Example'),
),
body: FutureBuilder(
future: fetchUser(),
builder: (context, snapshot) {
if (snapshot.connectionState ==
ConnectionState.waiting) {
return const Center(
child: CircularProgressIndicator(),
);
}
if (snapshot.hasError) {
return Center(
child: Text('Error: ${snapshot.error}'),
);
}
if (snapshot.hasData) {
final user = snapshot.data!;
return Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Text('ID: ${user.id}'),
Text('Name: ${user.name}'),
Text('Email: ${user.email}'),
],
),
);
}
return const Center(
child: Text('No user data available'),
);
},
),
),
);
}
}
When an API returns multiple records, the decoded list can be converted into model objects and displayed using ListView.builder.
Future> fetchUsers() async {
final response = await http.get(
Uri.parse('https://jsonplaceholder.typicode.com/users'),
);
if (response.statusCode != 200) {
throw Exception('Failed to load users');
}
final List data = jsonDecode(response.body);
return data
.map(
(item) => User.fromJson(
item as Map,
),
)
.toList();
}
Display the users:
FutureBuilder>(
future: fetchUsers(),
builder: (context, snapshot) {
if (snapshot.connectionState == ConnectionState.waiting) {
return const Center(
child: CircularProgressIndicator(),
);
}
if (snapshot.hasError) {
return Center(
child: Text('Error: ${snapshot.error}'),
);
}
final users = snapshot.data ?? [];
if (users.isEmpty) {
return const Center(
child: Text('No users found'),
);
}
return ListView.builder(
itemCount: users.length,
itemBuilder: (context, index) {
final user = users[index];
return ListTile(
title: Text(user.name),
subtitle: Text(user.email),
);
},
);
},
)
JSON processing is also required when sending data to an API.
Future createUser() async {
final user = {
'name': 'Rahul',
'email': '[email protected]',
};
final response = await http.post(
Uri.parse('https://example.com/api/users'),
headers: {
'Content-Type': 'application/json',
},
body: jsonEncode(user),
);
if (response.statusCode == 201) {
final data =
jsonDecode(response.body) as Map;
print(data);
} else {
throw Exception('Failed to create user');
}
}
APIs may return structured JSON when an operation fails.
{
"success": false,
"message": "Invalid email address",
"errors": {
"email": "Please enter a valid email"
}
}
The application can read the error message:
if (response.statusCode != 200) {
final errorData =
jsonDecode(response.body) as Map;
final message =
errorData['message'] as String? ?? 'Something went wrong';
throw Exception(message);
}
For larger applications, JSON processing logic should be separated from the UI.
class UserService {
Future> fetchUsers() async {
final response = await http.get(
Uri.parse('https://example.com/api/users'),
);
if (response.statusCode != 200) {
throw Exception('Failed to load users');
}
final List data = jsonDecode(response.body);
return data
.map(
(item) => User.fromJson(
item as Map,
),
)
.toList();
}
}
The UI can then use the service instead of containing all networking and parsing logic.
A clean Flutter application can separate responsibilities into different layers.
lib/
├── models/
│ └── user.dart
├── services/
│ └── user_service.dart
├── screens/
│ └── users_screen.dart
├── widgets/
│ └── user_card.dart
└── main.dart
| Layer | Responsibility |
|---|---|
| Model | Represents and parses application data. |
| Service | Makes API requests and processes responses. |
| Screen | Manages the screen-level application state. |
| Widget | Displays reusable pieces of UI. |
Small JSON responses can usually be decoded directly. Very large JSON documents may require additional care because JSON parsing is computational work.
For large responses, parsing can be moved to a background isolate using Flutter's compute() function.
import 'dart:convert';
import 'package:flutter/foundation.dart';
List parseUsers(String responseBody) {
final List data = jsonDecode(responseBody);
return data
.map(
(item) => User.fromJson(
item as Map,
),
)
.toList();
}
Future> fetchUsers() async {
final response = await http.get(
Uri.parse('https://example.com/api/users'),
);
if (response.statusCode != 200) {
throw Exception('Failed to load users');
}
return compute(parseUsers, response.body);
}
This approach can help keep expensive JSON parsing work away from the main UI isolate when the response is sufficiently large.
final data = jsonDecode(response.body);Do not assume that every HTTP response contains the expected successful JSON structure.
@override
Widget build(BuildContext context) {
fetchUsers();
return const SizedBox();
}The build() method may execute many times, which can cause repeated requests.
dynamic user = jsonDecode(response.body);For larger applications, model classes provide clearer and safer access to API data.
final String phone = json['phone'] as String;If the API returns null, this can fail. Use nullable types or appropriate default values when necessary.
Always verify whether the API returns an object, list, nested object, or another structure before parsing it.
dart:convert for JSON encoding and decoding.fromJson() methods for JSON-to-object conversion.toJson() methods when objects need to be sent to an API.build().FutureBuilder or an appropriate state-management solution for asynchronous data.
| Operation | Meaning | Example |
|---|---|---|
| Deserialization | JSON to Dart object/data | jsonDecode() |
| Serialization | Dart object/data to JSON | jsonEncode() |
JSON String
↓
jsonDecode()
↓
Map / List
↓
Dart Model
Dart Model
↓
toJson()
↓
Map
↓
jsonEncode()
↓
JSON String
For small applications and simple models, manual fromJson() and toJson() methods are often sufficient. For larger applications with many models, code-generation approaches such as json_serializable can reduce repetitive serialization code.
factory User.fromJson(Map json) {
return User(
id: json['id'] as int,
name: json['name'] as String,
);
}
Suppose an API returns the following product:
{
"id": 101,
"name": "Laptop",
"price": 65000,
"inStock": true
}
class Product {
final int id;
final String name;
final double price;
final bool inStock;
const Product({
required this.id,
required this.name,
required this.price,
required this.inStock,
});
factory Product.fromJson(Map json) {
return Product(
id: json['id'] as int,
name: json['name'] as String,
price: (json['price'] as num).toDouble(),
inStock: json['inStock'] as bool,
);
}
}
final data =
jsonDecode(response.body) as Map;
final product = Product.fromJson(data);
print(product.name);
print(product.price);
print(product.inStock);
Some APIs wrap the actual records inside a data property.
{
"success": true,
"data": [
{
"id": 1,
"name": "Rahul"
},
{
"id": 2,
"name": "Priya"
}
]
}
The list can be extracted first:
final Map responseData =
jsonDecode(response.body) as Map;
final List data = responseData['data'] as List;
final users = data
.map(
(item) => User.fromJson(
item as Map,
),
)
.toList();
dart:convert.response.statusCode.response.body.jsonDecode().
Create a Flutter application that reads a list of products from a JSON API.
http package.Product model.Product.fromJson() method.jsonDecode().List.ListView.builder.
jsonDecode() do?jsonEncode() do?fromJson() method?toJson() method?response.statusCode?build()?FutureBuilder?
| Concept | Purpose |
|---|---|
dart:convert |
Provides JSON encoding and decoding functionality. |
jsonDecode() |
Converts JSON text into Dart data. |
jsonEncode() |
Converts Dart data into JSON text. |
response.body |
Contains the HTTP response body. |
fromJson() |
Converts JSON data into a Dart model. |
toJson() |
Converts a Dart model into JSON-compatible data. |
FutureBuilder |
Builds UI based on asynchronous Future states. |
statusCode |
Indicates the result of an HTTP request. |
compute() |
Can move expensive parsing work to a background isolate. |
Reading and processing JSON responses is an essential skill for Flutter application development. A typical workflow involves making an HTTP request, checking the response status, reading response.body, decoding the JSON using jsonDecode(), converting the decoded data into Dart model objects, handling errors and nullable values, and finally displaying the processed data in the Flutter UI.
For simple applications, manual JSON parsing can be sufficient. As an application grows, strongly typed model classes, service layers, reusable parsing methods, proper error handling, and code-generation solutions can make the code easier to maintain and scale.
